Inside Macintosh: QuickTime Components
Sequence grabber components load, configure, and unload your panel component. As part of this process, the sequence grabber installs your panel's dialog items into the settings dialog box and may open your component's resource file. Panel components provide a number of functions that allow the sequence grabber to manage its relationship with panel components. This section discusses those functions.
After opening a connection to your panel component, the sequence grabber identifies itself to your component by calling your SGPanelSetGrabber function. The sequence grabber then tries to determine whether your component can work with its associated channel component by calling your SGPanelCanRun function. The sequence grabber calls this function only if you have set the channelFlagHasDependency component flag to 1.
Once the sequence grabber has determined that your panel component can work with its channel component, the sequence grabber may open your component's resource file (unless you have set the channelFlagDontOpenResFile component flag to 1). Once it has opened the resource file, it passes the file's reference number to you by calling your SGPanelSetResFile function.
Next, the sequence grabber prepares to add your component's items to the settings dialog box. The sequence grabber obtains your item list by calling your SGPanelGetDITL function. Once it has installed the items, it calls your SGPanelInstall function, giving you an opportunity to set initial values.
Before the sequence grabber removes your items from the settings dialog box, it calls your SGPanelRemove function.
The SGPanelSetGrabber function allows a sequence grabber component to identify itself to your panel component. This is typically the first function the sequence grabber component calls after opening your panel component.
pascal ComponentResult SGPanelSetGrabber
(SeqGrabComponent s,
SeqGrabComponent sg);
A sequence grabber component calls your SGPanelSetGrabber function in order to identify itself to your panel component. Your component can use the provided connection to call sequence grabber functions, either to determine the characteristics of the current capture operation or to alter those characteristics.
The SGPanelCanRun function allows a sequence grabber component to determine whether your panel component can work with the current sequence grabber channel component.
pascal ComponentResult SGPanelCanRun (SeqGrabComponent s,
SGChannel c);
A sequence grabber component calls your SGPanelCanRun function in order to determine whether your component can work with a specified sequence grabber channel component and its associated hardware. If your component works only with certain hardware, you should support this function.
Set the channelFlagHasDependency component flag to 1 to cause the sequence grabber component to call this function.
The sequence grabber component provides you with a connection to the channel component in question. Your component should query the channel component to determine whether you can operate with it. You may want to use channel component functions to determine the characteristics of the digitization source attached to the channel. If your component can work with the specified channel, return a result code of noErr . Otherwise, return an appropriate sequence grabber or sequence grabber channel component result code.
If your panel component can only support a limited number of connections, you should regulate the number of active connections in your SGPanelCanRun function. Return a nonzero result code to indicate to the sequence grabber that your panel component cannot support the current connection.
Unless you instruct it otherwise, the sequence grabber component opens your panel component's resource file for you. The SGPanelSetResFile function allows the sequence grabber to pass you the resource file's reference number. The sequence grabber also calls this function when it closes your resource file.
pascal ComponentResult SGPanelSetResFile
(SeqGrabComponent s,
short resRef);
A sequence grabber component calls your SGPanelSetResFile function in order to pass you your component's resource file reference number. By default, the sequence grabber component opens your component's resource file for you. You can use this reference number to retrieve resources from your resource file.
The sequence grabber component also calls this function when it closes your component's resource file. In this case, it sets the resRef parameter to 0. Note that the sequence grabber component may close your resource file at any time; you should not count on any particular calling sequence.
If you do not want the sequence grabber component to open your resource file, set the channelFlagDontOpenResFile component flag to 1.
The SGPanelGetDITL function allows a sequence grabber component to determine the dialog items managed by your panel component. The sequence grabber uses this information to build the sequence grabber settings dialog box for the user.
pascal ComponentResult SGPanelGetDITL (SeqGrabComponent s,
Handle *ditl);
A sequence grabber component calls your SGPanelGetDITL function in order to obtain the list of dialog items supported by your panel component. The sequence grabber then places these items into the settings dialog box and presents the dialog box to the user. When the sequence grabber builds the settings dialog box, it places your items appropriately--you do not need to specify particular locations for the items.
Your component returns the item list in a handle that is provided by the sequence grabber component. Note that the sequence grabber component will dispose of this handle after retrieving the item list, so make sure that the item list is not stored in a resource. If your item list is in a resource handle, you can use the Resource Manager's DetachResource routine to convert that resource handle into a handle that is suitable for use with the SGPanelGetDITL function.
The sequence grabber component will open your resource file before calling this function unless you have instructed the sequence grabber component not to open your resource file (that is, you have set the channelFlagDontOpenResFile component flag to 1).
A sequence grabber component calls your SGPanelInstall function after adding your items to the settings dialog box, just before it displays the dialog box to the user.
pascal ComponentResult SGPanelInstall (SeqGrabComponent s,
SGChannel c, DialogPtr d,
short itemOffset);
A sequence grabber component calls your SGPanelInstall function just before displaying the dialog box to the user. The sequence grabber provides you with information identifying the channel that your panel is to configure, the dialog box, and the offset of your panel's items into the dialog box. You may use this opportunity to set default dialog values or to initialize your control values.
Sequence grabber components call your component's SGPanelRemove function before removing your panel from the settings dialog box.
pascal ComponentResult SGPanelRemove (SeqGrabComponent s,
SGChannel c, DialogPtr d,
short itemOffset);
A sequence grabber component calls your SGPanelRemove function just before removing your items from the settings dialog box. The sequence grabber provides you with information identifying the channel your panel is to configure, the dialog box, and the offset of your panel's items into the dialog box. You may use this opportunity to save any changes you may have made to the dialog box or to retrieve the contents of TextEdit items.
If the sequence grabber opened your resource file, it will still be open when it calls this function.